SourceSync React Native SDK

The SourceSync React Native SDK allows you to easily integrate SourceSync experiences into your React Native applications. This SDK provides a seamless way to embed and control the SourceSync player or overlay within your app, with with full support for React Native's styling and layout system.

Installation

Install the package using npm:

npm install sourcesync-react-native-sdk

Or using yarn:

yarn add sourcesync-react-native-sdk

Usage

Here's a basic example of how to use the SourceSync React Native SDK with rendering:

import React, { useEffect } from 'react';
import { View, StyleSheet, Dimensions } from 'react-native';
import { Experience } from 'sourcesync-react-native-sdk';

function App() {
  const experience = new Experience({ key: 'your-api-key', session: yourSessionData });

  useEffect(() => {
    const handlePause = (experienceId) => {
      console.log(experienceId, 'was paused!');
    };

    experience.on('pause', handlePause);

    return () => {
      // Clean up event listeners if necessary
    };
  }, []);

  return (
    <View style={styles.container}>
      <experience.render style={styles.experience} />
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
  },
  experience: {
    width: '100%',
    height: '50%', // Takes up half the screen height
  },
});

export default App;

API Reference

Experience Class

Constructor

const experience = new Experience(options);

• options (Object): Configuration options for the experience.
  • key (string): Your SourceSync API key.
  • session (JSON): Your session object (for analytics).
  • settings (JSON): Optional overrides for the experience.

Methods

• on(eventName: string, callback: Function): Add an event listener.
• send(eventName: string, payload: string): Send a realtime message to SourceSync.
• play(): Play the experience.
• pause(): Pause the experience.
• setCurrentTime(time: number): Set the current time of the experience.
• mode(orientation: 'portrait' | 'landscape'): Set the orientation mode.
• render({ style: ViewStyle }): Render the experience component.
• async getActivations(filter: string): Returns a list of activations currently within the experience. optionally, you can query them.
• async getMetadata(filter: string): Returns a list of metadata associated with the media.
• async getMedia(filter: string): Returns details about the media in the experience.
• async getMoment(filter: string): Returns details about the context of the current moment. This will change depending on the current time and settings.
• async getEffects(moment): Returns SourceSync effects, given the current moment. If you don't provide a moment, the current one will be used.

Render events

Note these events will only fire if you're using the SourceSync render in player or overlay mode; they won't fire unless you're using experience.render.

• 'pause': Fired when the experience is paused.
• 'play': Fired when the experience is played.
• 'exit': Fired when the experience exits the render system.
• 'seek': Fired when the experience is beeing seeked to a new time.
• 'activationShowPreview': Fired when an activation preview is being displayed. Prevent default to use your own preview system!
• 'activationHidePreview': Fired when an activation preview is being hidden.
• 'activationShowDetail': Fired when an activation is opened in detail mode. Prevent default to use your own detail render system!
• 'activationHideDetail': Fired when an activation detail mode is closed.

Data events

These events fire when data changes or is available. Use them if you don't want to use the built-in render system and you just want to access the data directly.

• 'moment': Fired when a new moment is available.
• 'effect': Fired when new monetization or other effects are available.
• 'event': Fired when a realtime event has been sent to your client.

Styling and Layout

The SourceSync React Native SDK is designed to work seamlessly with React Native's styling and layout system. You can use standard React Native styles to control the size, position, and appearance of the experience within your app.

Here are some examples of how you can style the experience:

Percentage-based sizing

const styles = StyleSheet.create({
  experience: {
    width: '100%',  // Full width of parent
    height: '50%',  // Half height of parent
  },
});

Fixed dimensions

const styles = StyleSheet.create({
  experience: {
    width: 300,
    height: 200,
  },
});

Responsive sizing

import { Dimensions } from 'react-native';

const windowWidth = Dimensions.get('window').width;
const styles = StyleSheet.create({
  experience: {
    width: windowWidth,
    height: (windowWidth * 9) / 16, // 16:9 aspect ratio
  },
});

Flex layout

const styles = StyleSheet.create({
  container: {
    flex: 1,
  },
  experience: {
    flex: 1,  // Takes up all available space
  },
});

Remember to consider different device orientations and sizes. You might want to add event listeners for dimension changes to adjust your layout when the device rotates.

Examples

Creating and Controlling an Experience

import { Experience } from 'sourcesync-react-native-sdk';

const experience = new Experience({ key: 'your-api-key', session: yourSessionData });

// Play the experience
experience.play();

// Pause the experience
experience.pause();

// Set the current time
experience.setCurrentTime(30); // Set to 30 seconds

// Change orientation
experience.mode('landscape');

// Listen for events
experience.on('activationOpen', (activation) => {
  console.log('Activation opened:', activation);
});

Working with data directly

You can build or use your own unique render system; every aspect of our platform is exposed for you.

import { Experience } from 'sourcesync-react-native-sdk';

// Load an experience by distribution
const experience = new Experience({ distributionId: 123 });

// Get metadata for a specific time range
const metadata = experience.getMetadata({ start: 10000, duration: 10000 });

// Gets a moment (includes user, media, environmental context, as well as metadata)
const moment = experience.getMoment({ start: 10000, duration: 10000 });

// Try and monetize that moment (an event called 'effect' will come back if monetization opportunities are available)...
experience.send(moment)

// Syncronize with your own player...
myExistingPlayer.on('setCurrentTime', (time) => {
  experience.setCurrentTime(time)
});

// Do something when new effects occur...
experience.on('effect', (effect) => {
  console.log('These effects just came in:', effect)
});

// Handle incomming realtime messages (chat, etc)...
experience.on('event', (event) => {
  const { name, payload } = event
  console.log(`${name} was fired with ${payload}`)
});

License

This SDK is distributed under the Apache License, Version 2.0. The Apache 2.0 License applies to the SDK only and not any other component of the SourceSync Platform.

Support

If you encounter any issues or have questions, please file an issue on our GitHub issue tracker.